Reviewed at 5e42659 (R1).

Third PR in the media-use stack (base = #2065). Wires up usage visibility:

• Migrates the media-use anon-id from ~/.media/anon-id → the CLI/studio-shared ~/.hyperframes/config.json.anonymousId, so a person is one PostHog profile across surfaces (verified: CLI at packages/cli/src/telemetry/config.ts:17,70,87,98 uses the same field name at the same path).
• Adds $identify linking anon → HeyGen account (email or username) on sign-in — read from ~/.heygen/credentials.user per the CLI's own store schema (packages/cli/src/auth/store.ts:75 has KNOWN_USER_KEYS = {email, first_name, last_name, username}), so the schema assumption is correct.
• New resolve --stats (human + --json) + --days N window: local report from .media/ + ~/.media + a new ~/.media/misses.jsonl local miss log. Miss log captures intent text (local only) while the telemetry event media_use_resolve_miss deliberately does NOT — the dashboard doc calls this pairing out explicitly. Clean separation.
• New ~/.media/telemetry-notice-shown marker for the media-use first-run stderr notice.
• New references/telemetry-dashboard.md — reproducible PostHog dashboard definition. Good doc.

Rubric verifications:

• Cohort mixing / shared identity — intentional; every event carries surface: "media-use" for facetability. ✅
• Sibling-metric tag-set symmetry — resolve carries type/source/provider/via/local_only/provider_override; resolve_miss correctly drops provider and via (there is none for a miss); doctor carries ok/checks_failed/failed[]. Consistent. ✅
• Field conflation / verify at writer — anonymousId() reads from and writes to the exact shared config field the CLI reads/writes. ✅
• Hardcoded default in new writer — none; $identify only fires when a real email/username is present. ✅

Four inline findings (2 🟠 + 2 🟡):

• 🟠 Notice-shown state is split from the shared config (~/.media/telemetry-notice-shown vs CLI's config.telemetryNoticeShown). Users who saw the CLI notice will see media-use's separately — undermines the "one profile" architecture.
• 🟠 No migration path from the old ~/.media/anon-id file. media-use-only users get a fresh persona ID on upgrade; PostHog will show a cohort discontinuity on merge day.
• 🟡 --days doesn't validate — negative / zero / non-numeric silently produces empty stats that look like "no activity."
• 🟡 buildStats outer catch zeroes the whole report on any error, no signal that partial data failed to load.

Meta: PR body is a template stub ("Brief description of the change"). Reviewers have to read the diff top-to-bottom to figure out scope. Fill it in before merge — the shape is unusually large for the effort of a body.

CI: preview-regression + regression pass; regression-shards + Preflight lint-format skipping via detect-changes gate; Graphite mergeability check pending only. No red required checks. mergeable = MERGEABLE.

Zero blockers. Ready from where I sit once the 🟠s are decided and the body is filled in.

— Review by Rames D Jusso

R1 — hyperframes #2113 at 5e426596923fe48dae19f1c3bf7c75bbd4dc102f

Landing after Rames D Jusso's R1 at 21:34Z. Same head SHA, concurring on his four inline findings (2 🟠 + 2 🟡) with independent verification. My lens on this one is identity + disclosure + PII-boundary mechanic; Rames already covered the cohort-continuity, sibling-metric symmetry, and stats robustness angles. Not repeating his rubric — extending where I have independent signal.

Concurring with Rames — all four verified

• 🟠 Notice-shown state split (telemetry.mjs:78) — verified and this is the tightest of the four. The whole thesis of the PR (per the comment at :1-7) is "the same install id from ~/.hyperframes/config.json, plus a $identify to the HeyGen account on sign-in, so a person is one PostHog profile across surfaces." But showTelemetryNotice writes its shown-marker to a media-use-owned path (~/.media/telemetry-notice-shown) instead of a boolean on the shared config. A user who's already run the hyperframes CLI and dismissed its telemetry notice — same person, same identity, per this PR's own architecture — gets re-noticed on their first media-use invocation. Rames's option (a) (share the config.telemetryNoticeShown field) is the identity-preserving move; option (b) (a distinct mediaUseNoticeShown field on the same shared config) is defensible if the disclosure text needs to stay media-use-specific because it names the HeyGen $identify linkage. My preference: (b) — the media-use notice explicitly discloses the account-linking behavior that the CLI notice doesn't, so the disclosures aren't interchangeable. But keeping the shown-state in the shared config either way. Non-blocking, but architectural-consistency worth naming.

• 🟠 No migration from ~/.media/anon-id — verified. anonymousId() at telemetry.mjs:37-58 reads ~/.hyperframes/config.json, but never consults the pre-existing ~/.media/anon-id file that the previous version of telemetry.mjs wrote to. Any media-use-only user (i.e. someone who has run resolve but never the hyperframes CLI or studio) has a stable UUID in .media/anon-id that will be orphaned on this upgrade. Test at telemetry.test.mjs:98-107 covers "shared config wins when both files exist" but not "adopt legacy when only the legacy file exists" — that's the missing path. Rames's suggested branch (if (!parsed.anonymousId && existsSync(join(homedir(), ".media/anon-id"))) → read + copy into shared config) preserves cohort continuity. Concurring; the fix is one branch plus one test. From my identity-mechanic lens: this is essentially a schema migration masquerading as a config read. If it doesn't get done in this PR, whoever writes the PostHog dashboard next month is going to see a step-function of "new users" on merge day that isn't real activity.

• 🟡 --days validation (resolve.mjs:147) — verified. Number("garbage") === NaN, Number("-5") === -5, Number("0") === 0 all pass through resolve.mjs:145's args.days ? Number(args.days) : undefined and then into stats.mjs:80-82, which does Number(now) - Number(days) * 24 * 60 * 60 * 1000. The three failure modes Rames names (NaN → null cutoff silently, negative → future cutoff → all records fail window, zero → same as negative) all produce a stats report that reads as "no activity." A --stats diagnostic that renders zero on a bad --days is worse than useful — it lies to the user in the shape of a valid answer. Rames's fail-loud fix at flag-parse time (if (args.days !== undefined && !(Number(args.days) > 0)) exit(2)) is the right shape. Concurring.

• 🟡 buildStats outer catch swallowing errors (stats.mjs:116) — verified. try { ... } catch { return emptyReport(); } at :76-120 is the outermost guard. If readManifest(projectDir) throws on a subtle JSONL parse issue, or readGlobalManifest() blows up mid-walk, or diskBytes throws unexpectedly, the ENTIRE report zeroes out and the user sees total resolves: 0 / misses: 0 / hit rate: n/a. Reads as "no activity," not "some data failed to load." I'd initially clocked the outer catch as intentional-fail-safe; Rames is right that it swallows the wrong class of failure. Per-step try/catch with _partial: true marker in the JSON output (and a (partial data — some sources failed to load) line in the human output) is the correct shape. Concurring.

Identity + disclosure mechanic — my lens

Where Rames covered the verifier-of-schema angle (correctly linking ~/.heygen/credentials.user to packages/cli/src/auth/store.ts:75's KNOWN_USER_KEYS), I want to layer the disclosure semantic verification alongside:

• The first-run notice (telemetry.mjs:76-98) explicitly enumerates what's tracked (type/source/provider) AND what's not (intent text, file names, or paths) AND what changes on sign-in (links to your account email or username) AND how to opt out. That's the four disclosure elements a "coarse pseudonymous + account-linked-on-sign-in" model needs. Verified against the actual event shapes at resolve.mjs:344-355 (miss path — no intent), :1035 (hit path — no intent, no filename), :766 (candidates — counts only). The disclosure text matches the code truth. Good.
• $identify uses the raw email as distinct_id (via heygenAccountDistinctId at :60-74). That's the standard PostHog identity-stitching move — but it does put the email in PostHog data-at-rest in cleartext. Disclosed to the user, so consented. If the team ever wants to soften data-at-rest posture without sacrificing profile stitching, hashing the email as distinct_id while adding a person-property heygen_username gets the same stitching without cleartext. Purely a forward note; the current design is honest and non-surprising and does what the notice says it does.
• Notice fires on first track() call, so --stats and --doctor interact with it differently. --doctor calls track("media_use_doctor_run", ...) at resolve.mjs:131 → notice fires. --stats does NOT call track() — so a user whose first invocation is --stats gets local aggregates without ever seeing the disclosure. Two ways to close this: (a) call showTelemetryNotice() from the --stats branch too — one line at resolve.mjs:144, and semantically fits since --stats is itself a usage-visibility affordance; (b) live with the gap since --stats doesn't itself send anything to PostHog. Not blocking, but (a) is one line and free.
• $ip: null is stamped per event at telemetry.mjs:141 — IP is suppressed at ingest, not just filtered downstream. Verified. Good.
• Concurrency on ~/.hyperframes/config.json write: two processes racing on writeFileSync can drop the loser's UUID. Since both read on next boot, this converges — but the window produces one $identify event that never subsequently reconciles. Very minor, real, not blocking. Same class of issue Rames's migration concern raises in a different flavor: any time the shared config is a writer surface for multiple tools, races are possible. If the shared-config schema grows, a file-lock on the hyperframes-CLI side would be a defense.

Miss log — local-only, PII-safe

Not repeating Rames's coverage of the "intent local, telemetry coarse" separation — he named it and it's clean. Adding one small privacy note: ~/.media/misses.jsonl stores raw intent strings on disk unencrypted. On a shared machine or a synced volume ($HOME under iCloud Documents or Dropbox), those intents replicate. Not new to this PR — the manifest also lives under .media — but a future disclosure pass could clarify "not sent to PostHog" vs "stored locally in .media." Skip unless chasing a customer-privacy hardening pass.

--stats disk-walk

Nit adjacent to Rames's stats robustness concern: stats.mjs:65-72's diskBytes does a synchronous statSync per global-cache entry every time --stats runs. For a heavy cache (thousands of assets) that's a real filesystem walk on the hot path of the flag. Not a blocker. Mention only in case someone runs --stats in a tight loop from a script.

PR body

Rames flagged the template-stub body — concurring. The disclosure surface here is substantial (shared identity migration + PII boundary + new stats affordance) and reviewers a week from now can't reverse-engineer intent from the diff alone. Filling in the body before merge — with the "one profile across surfaces" thesis + the disclosure summary + a note about the migration path (assuming it lands) — is worth 15 minutes to get right.

What I'm NOT re-scoring

Rames's rubric already covers: cohort-mixing intent, sibling-metric tag-set symmetry, verify-at-writer for anonymousId, hardcoded-default check for $identify, CI signal. Consulted, concurred, moved on.

R1 by Via — clean thesis; four legitimate follow-ups from Rames all confirmed; disclosure design is honest and non-surprising.